CWinHttpRequest Class

Wrapper class for Microsoft WinHTTP Services, version 5.1

Methods

Events

Enumerations

HTTP Status Codes

Abort

Aborts a WinHTTP Send method.

FUNCTION Abort () AS HRESULT

Return value

The return value is S_OK (0) on success or an error value otherwise.

Remarks

You can abort both asynchronous and synchronous Send methods. To abort a synchronous Send method, you must call Abort from within an IWinHttpRequestEvents event.

GetAllResponseHeaders

Gets all HTTP response headers.

FUNCTION GetAllResponseHeaders () AS CBSTR

Return value

The resulting header information.

GetLastResult

Returns S_OK (0) if successful or an error value otherwise.

Remarks

This method returns all of the headers contained in the most recent server response. The individual headers are delimited by a carriage return and line feed combination (ASCII 13 and 10). The last entry is followed by two delimiters (13, 10, 13, 10). Invoke this method only after the Send method has been called.

Example

#include once "windows.bi"
#include once "Afx/CWinHttpRequest.inc"
using Afx

' // Create an instance of the CWinHttpRequest class
DIM pWHttp AS CWinHttpRequest
' // Open an HTTP connection to an HTTP resource
pWHttp.Open "GET", "http://microsoft.com"
' // Send an HTTP request to the HTTP server
pWHttp.Send
' // Wait for response with a timeout of 5 seconds
DIM iSucceeded AS LONG = pWHttp.WaitForResponse(5)
' // Get the response headers
DIM cbsResponseHeaders AS CBSTR = pWHttp.GetAllResponseHeaders
PRINT cbsResponseHeaders

GetErrorInfo

Returns the description of the most recent OLE error in the current logical thread and clears the error state for the thread. It should be called as soon as possible after calling a method of this class. The numerical error code can obtained calling the GetLastResult method.

FUNCTION GetErrorInfo() AS CBSTR

Return value

A localized description of the error.

GetLastResult

Returns the last result code.

FUNCTION GetLastResult () AS HRESULT

Return value

The result code returned by the last executed method. The WinHttpRequest object uses the IErrorInfo interface to provide error data. A description of the error can be obtained calling the GetOleErrorInfo method.

GetOption

Retrieves a Microsoft Windows HTTP Services (WinHTTP) option value.

FUNCTION GetOption (BYVAL nOption AS WinHttpRequestOption) AS CVAR

Return value

Variant that contains the option value.

Example

#include once "Afx/CWinHttpRequest.inc"
using Afx

' // Create an instance of the CWinHttp class
DIM pWHttp AS CWinHttpRequest
' // Open an HTTP connection to an HTTP resource
pWHttp.Open "GET", "http://microsoft.com"
' // Specify the user agent
pWHttp.SetOption(WinHttpRequestOption_UserAgentString, "A WinHttpRequest Example Program")
' // Send an HTTP request to the HTTP server
pWHttp.Send
IF pWHttp.GetLastResult = S_OK THEN
   ' // Get user agent string.
   PRINT pWHttp.GetOption(WinHttpRequestOption_UserAgentString)
   ' // Get URL
   PRINT pWHttp.GetOption(WinHttpRequestOption_URL)
   ' // Get URL Code Page.
   PRINT pWHttp.GetOption(WinHttpRequestOption_URLCodePage)
   ' // Convert percent symbols to escape sequences.
   PRINT pWHttp.GetOption(WinHttpRequestOption_EscapePercentInURL)
END IF
Sleep

GetLastResult

Returns S_OK (0) if successful or an error value otherwise.

GetResponseBody

Retrieves the response entity body as an array of unsigned bytes.

FUNCTION GetResponseBody () AS STRING

Return value

An string containing the response entity body as an array of unsigned bytes. This array contains the raw data as received directly from the server.

GetLastResult

Returns S_OK (0) if successful or an error value otherwise.

Remarks

This method returns the response data in an array of unsigned bytes. If the response does not have a response body, an empty variant is returned. This method can only be invoked after the Send method has been called.

Examples

#include once "Afx/CWinHttpRequest.inc"
using Afx

' // Create an instance of the CWinHttpRequest class
DIM pWHttp AS CWinHttpRequest
' // Open an HTTP connection to an HTTP resource
pWHttp.Open "GET", "http://microsoft.com"
' // Send an HTTP request to the HTTP server
pWHttp.Send
' // Wait for response with a timeout of 5 seconds
DIM iSucceeded AS LONG = pWHttp.WaitForResponse(5)
' // Get the response body
DIM strResponseBody AS STRING = pWHttp.GetResponseBody
PRINT strResponseBody

#include once "Afx/CWinHttpRequest.inc"
#include once "Afx/CStream.inc"
using Afx

' // Create an instance of the CWinHttpRequest class
DIM pWHttp AS CWinHttpRequest
' // Open an HTTP connection to an HTTP resource
pWHttp.Open "GET", "https://i.ytimg.com/vi/nPUi1XNiRzQ/maxresdefault.jpg"
print pWHttp.GetErrorInfo
' // Send an HTTP request to the HTTP server
pWHttp.Send
' // Wait for response with a timeout of 5 seconds
DIM iSucceeded AS LONG = pWHttp.WaitForResponse(5)
' // Get the reponse body and sae it into a file
DIM st AS STRING = pWHttp.GetResponseBody
' // Open a file stream
DIM pFileStream AS CFileStream
IF pFileStream.Open("image.jpg", STGM_CREATE OR STGM_WRITE) = S_OK then
   pFileStream.WriteTextA(st)
END IF

GetResponseHeader

Gets the specified HTTP response header.

FUNCTION GetResponseHeader (BYREF cbsHeader AS CBSTR) AS CBSTR

Return value

The resulting header information.

GetLastResult

Returns S_OK (0) if successful or an error value otherwise.

Remarks

Invoke this method only after the Send method has been called.

Example

#include "Afx/CWinHttpRequest.inc"
using Afx

' // Create an instance of the CWinHttpRequest class
DIM pWHttp AS CWinHttpRequest
' // Open an HTTP connection to an HTTP resource
pWHttp.Open "GET", "http://microsoft.com"
' // Send an HTTP request to the HTTP server
pWHttp.Send
' // Wait for response with a timeout of 5 seconds
DIM iSucceeded AS LONG = pWHttp.WaitForResponse(5)
' // Get the response headers
DIM cbsResponseHeader AS CBSTR = pWHttp.GetResponseHeader("Date")
PRINT cbsResponseHeader

GetResponseStream

Retrieves the response entity body as a stream.

FUNCTION GetResponseStream () AS IStream PTR

Return value

Returns a pointer to an IStream interface if successful or NULL otherwise.

GetLastResult

Returns S_OK (0) if successful or an error value otherwise.

Remarks

This method can only be invoked after the Send method has been called.

GetResponseText

Retrieves the response entity body as a CBSTR.

FUNCTION GetResponseText () AS CBSTR

Return value

A CBSTR containing the entity body of the response as text.

GetLastResult

Returns S_OK (0) if successful or an error value otherwise.

Remarks

This method can only be invoked after the Send method has been called.

When using this property in synchronous mode, the limit to the number of characters it returns is approximately 2,169,895.

GetStatus

Retrieves the HTTP status code from the last response.

FUNCTION GetStatus () AS LONG

Return value

Value of type LONG that receives the returned status code.

GetLastResult

Returns S_OK (0) if successful or an error value otherwise.

Remarks

The results of this method are valid only after the Send method has successfully completed. For a list of status codes see HTTP Status Codes.

GetStatusText

Retrieves the HTTP status code from the last response.

FUNCTION GetStatusText () AS CBSTR

Return value

A CBSTR containing the HTTP status text.

GetLastResult

Returns S_OK (0) if successful or an error value otherwise.

Remarks

Retrieves the text portion of the server response line, making available the "user-friendly" equivalent to the numeric HTTP status code. The results of this property are valid only after the Send method has successfully completed.

Open

Opens an HTTP connection to an HTTP resource.

FUNCTION Open (BYREF cbsMethod AS CBSTR, BYREF cbsUrl AS CBSTR, BYVAL bAsync AS BOOLEAN = FALSE) AS HRESULT

Return value

The return value is S_OK (0) on success or an error value otherwise.

Remarks

This method opens a connection to the resource identified in cbsUrl using the HTTP verb given in cbsMethod.

Example

#include "Afx/CWinHttpRequest.inc"
using Afx

' // Create an instance of the CWinHttpRequest class
DIM pWHttp AS CWinHttpRequest
' // Open an HTTP connection to an HTTP resource
pWHttp.Open "GET", "http://microsoft.com"
' // Send an HTTP request to the HTTP server
pWHttp.Send
' // Wait for response with a timeout of 5 seconds
DIM iSucceeded AS LONG = pWHttp.WaitForResponse(5)

Send

Sends an HTTP request to an HTTP server.

FUNCTION Send (BYREF cvBody AS CVAR = "") AS HRESULT

Return value

Returns S_OK (0) if successful or an error value otherwise.

Remarks

The request to be sent was defined in a prior call to the Open method. The calling application can provide data to be sent to the server through the cvBody parameter. If the HTTP verb of the object's Open is "GET", this method sends the request without cvBody, even if it is provided by the calling application.

SetAutoLogonPolicy

Sets the current Automatic Logon Policy.

FUNCTION SetAutoLogonPolicy (BYVAL AutoLogonPolicy AS WinHttpRequestAutoLogonPolicy) AS HRESULT

Return value

Returns S_OK (0) if successful or an error value otherwise.

Remarks

The default policy is AutoLogonPolicy_OnlyIfBypassProxy.

Call SetAutoLogonPolicy to set the automatic logon policy before calling Send to send the request.

SetClientCertificate

Selects a client certificate to send to a Secure Hypertext Transfer Protocol (HTTPS) server.

FUNCTION SetClientCertificate (BYREF cbsClientCertificate AS CBSTR) AS HRESULT

Return value

Returns S_OK (0) if successful or an error value otherwise.

Remarks

The string specified in the cbsClientCertificate parameter consists of the certificate location, certificate store, and subject name delimited by backslashes. For more information about the components of the certificate string, see Client Certificates.

The certificate store name and location are optional. However, if you specify a certificate store, you must also specify the location of that certificate store. The default location is CURRENT_USER and the default certificate store is "MY". A blank subject indicates that the first certificate in the certificate store should be used.

Call SetClientCertificate to select a certificate before calling Send to send the request.

Microsoft Windows HTTP Services (WinHTTP) does not provide client certificates to proxy servers that request certificates for authentication.

SetCredentials

Sets credentials to be used with an HTTP server, whether it is a proxy server or an originating server.

FUNCTION SetCredentials (BYREF cbsUserName AS CBSTR, BYREF cbsPassword AS CBSTR, _
   BYVAL Flags AS HTTPREQUEST_SETCREDENTIALS_FLAGS) AS HRESULT

Return value

Returns S_OK (0) if successful or an error value otherwise.

Remarks

This method returns an error value if a call to Open has not completed successfully. It is assumed that some measure of interaction with a proxy server or origin server must occur before users can set credentials for the session. Moreover, until users know which authentication scheme(s) are supported, they cannot format the credentials.

To authenticate with both the server and the proxy, the application must call SetCredentials twice; first with the Flags parameter set to HTTPREQUEST_SETCREDENTIALS_FOR_SERVER, and second, with the Flags parameter set to HTTPREQUEST_SETCREDENTIALS_FOR_PROXY.

SetOption

Sets a Microsoft Windows HTTP Services (WinHTTP) option value.

FUNCTION SetOption (BYVAL nOption AS WinHttpRequestOption, BYREF cvValue AS CVAR) AS HRESULT

Return value

Returns S_OK (0) if successful or an error value otherwise.

Example

#include once "Afx/CWinHttpRequest.inc"
using Afx

' // Create an instance of the CWinHttp class
DIM pWHttp AS CWinHttpRequest
' // Open an HTTP connection to an HTTP resource
pWHttp.Open "GET", "http://microsoft.com"
' // Specify the user agent
pWHttp.SetOption(WinHttpRequestOption_UserAgentString, "A WinHttpRequest Example Program")
' // Send an HTTP request to the HTTP server
pWHttp.Send
IF pWHttp.GetLastResult = S_OK THEN
   ' // Get user agent string.
   PRINT pWHttp.GetOption(WinHttpRequestOption_UserAgentString)
   ' // Get URL
   PRINT pWHttp.GetOption(WinHttpRequestOption_URL)
   ' // Get URL Code Page.
   PRINT pWHttp.GetOption(WinHttpRequestOption_URLCodePage)
   ' // Convert percent symbols to escape sequences.
   PRINT pWHttp.GetOption(WinHttpRequestOption_EscapePercentInURL)
END IF
Sleep

SetProxy

Sets proxy server information.

FUNCTION SetProxy (BYVAL ProxySetting AS HTTPREQUEST_PROXY_SETTING, BYREF cvProxyServer AS CVAR = "", _
   BYVAL cvBypassList AS CVAR = "") AS HRESULT

Return value

Returns S_OK (0) if successful or an error value otherwise.

Remarks

Enables the calling application to specify use of default proxy information (configured by the proxy configuration tool) or to override Proxycfg.exe. This method must be called before calling the Send method. If this method is called after the Send method, it has no effect.

CWinHttpRequest passes these parameters to Microsoft Windows HTTP Services (WinHTTP).

SetRequestHeader

Adds, changes, or deletes an HTTP request header.

FUNCTION SetRequestHeader (BYREF cbsHeader AS CBSTR, BYREF cbsValue AS CBSTR) AS HRESULT

Return value

Returns S_OK if successful or an error value otherwise.

Remarks

Headers are transferred across redirects. This can create a security vulnerability. To avoid having headers transferred if a redirect occurs, use the WINHTTP_STATUS_CALLBACK callback to correct the specific headers when a redirect occurs.

The SetRequestHeader method enables the calling application to add or delete an HTTP request header prior to sending the request. The header name is given in cbsHeader, and the header token or value is given in cbsValue. To add a header, supply a header name and value. If another header already exists with this name, it is replaced. To delete a header, set cbsHeader to the name of the header to delete and set cbsValue to NULL.

The name and value of request headers added with this method are validated. Headers must be well formed. For more information about valid HTTP headers, see RFC 2616. If an invalid header is used, an error occurs and the header is not added.

SetTimeouts

Specifies the individual time-out components of a send/receive operation, in milliseconds.

FUNCTION SetTimeouts (BYVAL ResolveTimeout AS LONG, BYVAL ConnectTimeout AS LONG, _
   BYVAL SendTimeout AS LONG, BYVAL ReceiveTimeout AS LONG) AS HRESULT

Return value

Returns S_OK (0) if successful or an error value otherwise.

Remarks

All parameters are required. A value of 0 or -1 sets a time-out to wait infinitely. A value greater than 0 sets the time-out value in milliseconds. For example, 30,000 would set the time-out to 30 seconds. All negative values other than -1 cause this method to fail.

Time-out values are applied at the Winsock layer.

WaitForResponse

Waits for an asynchronous Send method to complete, with optional time-out value, in seconds.

FUNCTION WaitForResponse (BYVAL nTimeout AS LONG = 0) AS BOOLEAN

Return value

TRUE or FALSE.

Remarks

This method suspends execution while waiting for a response to an asynchronous request. This method should be called after a Send. Calling applications can specify an optional Timeout value, in seconds. If this method times out, the request is not aborted. This way, the calling application can continue to wait for the request, if desired, in a subsequent call to this method.

Calling this property after a synchronous Send method returns immediately and has no effect.

WinHttpRequestAutoLogonPolicy Enumeration

The WinHttpRequestAutoLogonPolicy enumeration includes possible settings for the Automatic Logon Policy.

Remarks

To set the automatic logon policy, call the SetAutoLogonPolicy method and specify one of the preceding constants.

WinHttpRequestOption Enumeration

The WinHttpRequestOption enumeration includes options that can be set or retrieved for the current Microsoft Windows HTTP Services (WinHTTP) session.

Remarks

Set an option by specifying one of the preceding constants as the parameter of the Option property.

WinHttpRequestSecureProtocols Enumeration

Types of secure protocols.

WinHttpRequestSslErrorFlags Enumeration

SSL certificate errors.

HTTP Status Codes

These constants and corresponding values indicate HTTP status codes returned by servers on the Internet.

OnError Event

Occurs when there is a run-time error in the application.

SUB OnError (BYVAL ErrorNumber AS LONG, BYVAL ErrorDescription AS BSTR)

OnResponseDataAvailable Event

Occurs when data is available from the response.

SUB OnResponseDataAvailable (BYVAL pData AS SAFEARRAY PTR)

OnResponseFinished Event

Occurs when the response data is complete.

SUB OnResponseFinished

OnResponseStart Event

Occurs when the response data starts to be received.

SUB OnResponseStart (BYVAL Status AS LONG, BYVAL ContentType AS BSTR)

Remarks

For this event to occur, use Open to send an HTTP connection in asynchronous mode and use Send to send a data request to an Internet server. This is the first WinHTTP event to occur after the Send.